oagi-core 0.10.1__py3-none-any.whl

oagi/__init__.py

@@ -0,0 +1,148 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+import importlib
+from typing import TYPE_CHECKING
+
+from oagi.client import AsyncClient, SyncClient
+from oagi.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    NotFoundError,
+    OAGIError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    ValidationError,
+    check_optional_dependency,
+)
+from oagi.task import Actor, AsyncActor, AsyncShortTask, AsyncTask, ShortTask, Task
+from oagi.types import ImageConfig
+from oagi.types.models import (
+    ErrorDetail,
+    ErrorResponse,
+    GenerateResponse,
+    LLMResponse,
+    UploadFileResponse,
+)
+
+# Lazy imports for optional dependency modules
+# Format: name -> (module_path, package_to_check, extra_name)
+# package_to_check is None if no optional dependency is required
+_LAZY_IMPORTS_DATA: dict[str, tuple[str, str | None, str | None]] = {
+    # Desktop handlers (require pyautogui/PIL)
+    "AsyncPyautoguiActionHandler": (
+        "oagi.handler.async_pyautogui_action_handler",
+        "pyautogui",
+        "desktop",
+    ),
+    "AsyncScreenshotMaker": ("oagi.handler.async_screenshot_maker", "PIL", "desktop"),
+    "PILImage": ("oagi.handler.pil_image", "PIL", "desktop"),
+    "PyautoguiActionHandler": (
+        "oagi.handler.pyautogui_action_handler",
+        "pyautogui",
+        "desktop",
+    ),
+    "PyautoguiConfig": (
+        "oagi.handler.pyautogui_action_handler",
+        "pyautogui",
+        "desktop",
+    ),
+    "ScreenshotMaker": ("oagi.handler.screenshot_maker", "PIL", "desktop"),
+    # Agent modules (lazy to avoid circular imports)
+    "AsyncDefaultAgent": ("oagi.agent.default", None, None),
+    "TaskerAgent": ("oagi.agent.tasker", None, None),
+    "AsyncAgentObserver": ("oagi.agent.observer.agent_observer", None, None),
+    # Server modules (require server dependencies)
+    "create_app": ("oagi.server.main", "socketio", "server"),
+    "ServerConfig": ("oagi.server.config", "pydantic_settings", "server"),
+    "sio": ("oagi.server.socketio_server", "socketio", "server"),
+}
+
+if TYPE_CHECKING:
+    from oagi.agent.default import AsyncDefaultAgent
+    from oagi.agent.observer.agent_observer import AsyncAgentObserver
+    from oagi.agent.tasker import TaskerAgent
+    from oagi.handler.async_pyautogui_action_handler import AsyncPyautoguiActionHandler
+    from oagi.handler.async_screenshot_maker import AsyncScreenshotMaker
+    from oagi.handler.pil_image import PILImage
+    from oagi.handler.pyautogui_action_handler import (
+        PyautoguiActionHandler,
+        PyautoguiConfig,
+    )
+    from oagi.handler.screenshot_maker import ScreenshotMaker
+    from oagi.server.config import ServerConfig
+    from oagi.server.main import create_app
+    from oagi.server.socketio_server import sio
+
+
+def __getattr__(name: str):
+    """Lazy import for optional dependency modules with helpful error messages."""
+    if name in _LAZY_IMPORTS_DATA:
+        module_path, package, extra = _LAZY_IMPORTS_DATA[name]
+        if package is not None:
+            check_optional_dependency(package, name, extra)
+        module = importlib.import_module(module_path)
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return all public names including lazy imports."""
+    return sorted(set(globals().keys()) | set(_LAZY_IMPORTS_DATA.keys()))
+
+
+__all__ = [
+    # Core sync classes
+    "Actor",
+    "AsyncActor",
+    "Task",  # Deprecated: Use Actor instead
+    "ShortTask",  # Deprecated
+    "SyncClient",
+    # Core async classes
+    "AsyncTask",  # Deprecated: Use AsyncActor instead
+    "AsyncShortTask",  # Deprecated
+    "AsyncClient",
+    # Agent classes
+    "AsyncDefaultAgent",
+    "TaskerAgent",
+    "AsyncAgentObserver",
+    # Configuration
+    "ImageConfig",
+    # Response models
+    "LLMResponse",
+    "GenerateResponse",
+    "UploadFileResponse",
+    "ErrorResponse",
+    "ErrorDetail",
+    # Exceptions
+    "OAGIError",
+    "APIError",
+    "AuthenticationError",
+    "ConfigurationError",
+    "NetworkError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "RequestTimeoutError",
+    "ValidationError",
+    # Lazy imports - Image classes
+    "PILImage",
+    # Lazy imports - Handler classes
+    "PyautoguiActionHandler",
+    "PyautoguiConfig",
+    "ScreenshotMaker",
+    # Lazy imports - Async handler classes
+    "AsyncPyautoguiActionHandler",
+    "AsyncScreenshotMaker",
+    # Lazy imports - Server modules (optional)
+    "create_app",
+    "ServerConfig",
+    "sio",
+]

oagi/agent/__init__.py

@@ -0,0 +1,33 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+# Import factories to trigger registration
+from . import factories  # noqa: F401
+from .default import AsyncDefaultAgent
+from .observer import AsyncAgentObserver
+from .protocol import Agent, AsyncAgent
+from .registry import (
+    async_agent_register,
+    create_agent,
+    get_agent_factory,
+    list_agent_modes,
+)
+from .tasker import TaskeeAgent, TaskerAgent
+
+__all__ = [
+    "Agent",
+    "AsyncAgent",
+    "AsyncAgentObserver",
+    "AsyncDefaultAgent",
+    "TaskerAgent",
+    "TaskeeAgent",
+    "async_agent_register",
+    "create_agent",
+    "get_agent_factory",
+    "list_agent_modes",
+]

oagi/agent/default.py

@@ -0,0 +1,124 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import logging
+
+from .. import AsyncActor
+from ..types import (
+    ActionEvent,
+    AsyncActionHandler,
+    AsyncImageProvider,
+    AsyncObserver,
+    Image,
+    StepEvent,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _serialize_image(image: Image | str) -> bytes | str:
+    """Convert an image to bytes or keep URL as string."""
+    if isinstance(image, str):
+        return image
+    return image.read()
+
+
+class AsyncDefaultAgent:
+    """Default asynchronous agent implementation using OAGI client."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "lux-actor-1",
+        max_steps: int = 20,
+        temperature: float | None = 0.5,
+        step_observer: AsyncObserver | None = None,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url
+        self.model = model
+        self.max_steps = max_steps
+        self.temperature = temperature
+        self.step_observer = step_observer
+
+    async def execute(
+        self,
+        instruction: str,
+        action_handler: AsyncActionHandler,
+        image_provider: AsyncImageProvider,
+    ) -> bool:
+        async with AsyncActor(
+            api_key=self.api_key, base_url=self.base_url, model=self.model
+        ) as self.actor:
+            logger.info(f"Starting async task execution: {instruction}")
+            await self.actor.init_task(instruction, max_steps=self.max_steps)
+
+            for i in range(self.max_steps):
+                step_num = i + 1
+                logger.debug(f"Executing step {step_num}/{self.max_steps}")
+
+                # Capture current state
+                image = await image_provider()
+
+                # Get next step from OAGI
+                step = await self.actor.step(image, temperature=self.temperature)
+
+                # Log reasoning
+                if step.reason:
+                    logger.info(f"Step {step_num}: {step.reason}")
+
+                # Emit step event
+                if self.step_observer:
+                    await self.step_observer.on_event(
+                        StepEvent(
+                            step_num=step_num,
+                            image=_serialize_image(image),
+                            step=step,
+                        )
+                    )
+
+                # Execute actions if any
+                if step.actions:
+                    logger.info(f"Actions ({len(step.actions)}):")
+                    for action in step.actions:
+                        count_suffix = (
+                            f" x{action.count}"
+                            if action.count and action.count > 1
+                            else ""
+                        )
+                        logger.info(
+                            f"  [{action.type.value}] {action.argument}{count_suffix}"
+                        )
+
+                    error = None
+                    try:
+                        await action_handler(step.actions)
+                    except Exception as e:
+                        error = str(e)
+                        raise
+
+                    # Emit action event
+                    if self.step_observer:
+                        await self.step_observer.on_event(
+                            ActionEvent(
+                                step_num=step_num,
+                                actions=step.actions,
+                                error=error,
+                            )
+                        )
+
+                # Check if task is complete
+                if step.stop:
+                    logger.info(f"Task completed successfully after {step_num} steps")
+                    return True
+
+            logger.warning(
+                f"Task reached max steps ({self.max_steps}) without completion"
+            )
+            return False

oagi/agent/factories.py

@@ -0,0 +1,74 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+from oagi.agent.tasker import TaskerAgent
+from oagi.types import AsyncStepObserver
+
+from .default import AsyncDefaultAgent
+from .protocol import AsyncAgent
+from .registry import async_agent_register
+
+
+@async_agent_register(mode="actor")
+def create_default_agent(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    model: str = "lux-actor-1",
+    max_steps: int = 20,
+    temperature: float = 0.1,
+    step_observer: AsyncStepObserver | None = None,
+) -> AsyncAgent:
+    return AsyncDefaultAgent(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        max_steps=max_steps,
+        temperature=temperature,
+        step_observer=step_observer,
+    )
+
+
+@async_agent_register(mode="thinker")
+def create_thinker_agent(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    model: str = "lux-thinker-1",
+    max_steps: int = 100,
+    temperature: float = 0.1,
+    step_observer: AsyncStepObserver | None = None,
+) -> AsyncAgent:
+    return AsyncDefaultAgent(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        max_steps=max_steps,
+        temperature=temperature,
+        step_observer=step_observer,
+    )
+
+
+@async_agent_register(mode="tasker")
+def create_planner_agent(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    model: str = "lux-actor-1",
+    max_steps: int = 30,
+    temperature: float = 0.1,
+    reflection_interval: int = 20,
+    step_observer: AsyncStepObserver | None = None,
+) -> AsyncAgent:
+    tasker = TaskerAgent(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        max_steps=max_steps,
+        temperature=temperature,
+        reflection_interval=reflection_interval,
+        step_observer=step_observer,
+    )
+    # tasker.set_task()
+    return tasker

oagi/agent/observer/__init__.py

@@ -0,0 +1,38 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from ...types import (
+    ActionEvent,
+    AsyncObserver,
+    BaseEvent,
+    ImageEvent,
+    LogEvent,
+    ObserverEvent,
+    PlanEvent,
+    SplitEvent,
+    StepEvent,
+)
+from .agent_observer import AsyncAgentObserver, ExportFormat
+from .exporters import export_to_html, export_to_json, export_to_markdown
+
+__all__ = [
+    "ActionEvent",
+    "AsyncAgentObserver",
+    "AsyncObserver",
+    "BaseEvent",
+    "ExportFormat",
+    "ImageEvent",
+    "LogEvent",
+    "ObserverEvent",
+    "PlanEvent",
+    "SplitEvent",
+    "StepEvent",
+    "export_to_html",
+    "export_to_json",
+    "export_to_markdown",
+]

oagi/agent/observer/agent_observer.py

@@ -0,0 +1,99 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from enum import Enum
+
+from ...types import LogEvent, ObserverEvent, SplitEvent
+from .exporters import export_to_html, export_to_json, export_to_markdown
+
+
+class ExportFormat(str, Enum):
+    """Supported export formats."""
+
+    MARKDOWN = "markdown"
+    HTML = "html"
+    JSON = "json"
+
+
+class AsyncAgentObserver:
+    """Records agent execution events and exports to various formats.
+
+    This class implements the AsyncObserver protocol and provides
+    functionality for recording events during agent execution and
+    exporting them to Markdown or HTML formats.
+    """
+
+    def __init__(self) -> None:
+        self.events: list[ObserverEvent] = []
+
+    async def on_event(self, event: ObserverEvent) -> None:
+        """Record an event.
+
+        Args:
+            event: The event to record.
+        """
+        self.events.append(event)
+
+    def add_log(self, message: str) -> None:
+        """Add a custom log message.
+
+        Args:
+            message: The log message to add.
+        """
+        self.events.append(LogEvent(message=message))
+
+    def add_split(self, label: str = "") -> None:
+        """Add a visual separator.
+
+        Args:
+            label: Optional label for the separator.
+        """
+        self.events.append(SplitEvent(label=label))
+
+    def clear(self) -> None:
+        """Clear all recorded events."""
+        self.events.clear()
+
+    def get_events_by_step(self, step_num: int) -> list[ObserverEvent]:
+        """Get all events for a specific step.
+
+        Args:
+            step_num: The step number to filter by.
+
+        Returns:
+            List of events for the specified step.
+        """
+        return [
+            event
+            for event in self.events
+            if hasattr(event, "step_num") and event.step_num == step_num
+        ]
+
+    def export(
+        self,
+        format: ExportFormat | str,
+        path: str,
+        images_dir: str | None = None,
+    ) -> None:
+        """Export recorded events to a file.
+
+        Args:
+            format: Export format (markdown, html, json)
+            path: Path to the output file.
+            images_dir: Directory to save images (markdown only).
+        """
+        if isinstance(format, str):
+            format = ExportFormat(format.lower())
+
+        match format:
+            case ExportFormat.MARKDOWN:
+                export_to_markdown(self.events, path, images_dir)
+            case ExportFormat.HTML:
+                export_to_html(self.events, path)
+            case ExportFormat.JSON:
+                export_to_json(self.events, path)

oagi/agent/observer/events.py

@@ -0,0 +1,28 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+# Re-export from types for convenience
+from ...types import (
+    ActionEvent,
+    BaseEvent,
+    ImageEvent,
+    LogEvent,
+    ObserverEvent,
+    SplitEvent,
+    StepEvent,
+)
+
+__all__ = [
+    "ActionEvent",
+    "BaseEvent",
+    "ImageEvent",
+    "LogEvent",
+    "ObserverEvent",
+    "SplitEvent",
+    "StepEvent",
+]